package org.convallaria.system.biz.service.sys;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import org.convallaria.system.biz.entity.SysRole;

import java.util.List;
import java.util.Set;

/**
 * 系统角色服务接口
 * 
 * 功能特性：
 * - 角色基础CRUD操作
 * - 角色权限管理
 * - 角色用户关联管理
 * - 角色菜单关联管理
 * - 角色部门关联管理
 * - 角色缓存管理
 * 
 * @author convallaria
 * @since 1.0.0
 */
public interface SysRoleService extends IService<SysRole> {

    /**
     * 分页查询角色列表
     * 
     * @param pageNum 页码
     * @param pageSize 页大小
     * @param roleName 角色名称（可选）
     * @param roleKey 角色键值（可选）
     * @param status 状态（可选）
     * @param tenantId 租户ID（可选）
     * @return 角色分页列表
     */
    IPage<SysRole> pageRoles(Integer pageNum, Integer pageSize, String roleName, String roleKey, String status, Long tenantId);

    /**
     * 根据角色ID获取角色信息（带缓存）
     * 
     * @param roleId 角色ID
     * @return 角色信息
     */
    SysRole getRoleById(Long roleId);

    /**
     * 根据角色键值获取角色信息
     * 
     * @param roleKey 角色键值
     * @param tenantId 租户ID
     * @return 角色信息
     */
    SysRole getRoleByKey(String roleKey, Long tenantId);

    /**
     * 更新角色信息（清除相关缓存）
     * 
     * @param role 角色信息
     * @return 是否成功
     */
    boolean updateRole(SysRole role);

    /**
     * 删除角色（清除相关缓存）
     * 
     * @param roleId 角色ID
     * @return 是否成功
     */
    boolean deleteRole(Long roleId);

    /**
     * 批量删除角色（清除相关缓存）
     * 
     * @param roleIds 角色ID列表
     * @return 是否成功
     */
    boolean deleteRoles(List<Long> roleIds);

    /**
     * 刷新角色缓存
     * 
     * @param role 角色信息
     * @return 角色信息
     */
    SysRole refreshRoleCache(SysRole role);

    /**
     * 获取角色的菜单权限
     * 
     * @param roleId 角色ID
     * @return 菜单权限集合
     */
    Set<String> getRoleMenuPermissions(Long roleId);

    /**
     * 获取角色的部门权限
     * 
     * @param roleId 角色ID
     * @return 部门权限集合
     */
    Set<Long> getRoleDeptPermissions(Long roleId);

    /**
     * 分配角色菜单权限
     * 
     * @param roleId 角色ID
     * @param menuIds 菜单ID列表
     * @return 是否成功
     */
    boolean assignRoleMenus(Long roleId, List<Long> menuIds);

    /**
     * 分配角色部门权限
     * 
     * @param roleId 角色ID
     * @param deptIds 部门ID列表
     * @return 是否成功
     */
    boolean assignRoleDepts(Long roleId, List<Long> deptIds);

    /**
     * 获取用户的所有角色
     * 
     * @param userId 用户ID
     * @return 角色列表
     */
    List<SysRole> getUserRoles(Long userId);

    /**
     * 获取用户的角色键值集合
     * 
     * @param userId 用户ID
     * @return 角色键值集合
     */
    Set<String> getUserRoleKeys(Long userId);

    /**
     * 分配用户角色
     * 
     * @param userId 用户ID
     * @param roleIds 角色ID列表
     * @return 是否成功
     */
    boolean assignUserRoles(Long userId, List<Long> roleIds);

    /**
     * 取消用户角色
     * 
     * @param userId 用户ID
     * @param roleIds 角色ID列表
     * @return 是否成功
     */
    boolean unassignUserRoles(Long userId, List<Long> roleIds);

    /**
     * 检查角色名称是否唯一
     * 
     * @param roleName 角色名称
     * @param roleId 角色ID（更新时排除自己）
     * @param tenantId 租户ID
     * @return 是否唯一
     */
    boolean isRoleNameUnique(String roleName, Long roleId, Long tenantId);

    /**
     * 检查角色键值是否唯一
     * 
     * @param roleKey 角色键值
     * @param roleId 角色ID（更新时排除自己）
     * @param tenantId 租户ID
     * @return 是否唯一
     */
    boolean isRoleKeyUnique(String roleKey, Long roleId, Long tenantId);

    /**
     * 检查角色是否被用户使用
     * 
     * @param roleId 角色ID
     * @return 是否被使用
     */
    boolean isRoleInUse(Long roleId);

    /**
     * 获取角色的所有权限（菜单权限）
     * 
     * @param roleId 角色ID
     * @return 权限集合
     */
    Set<String> getRolePermissions(Long roleId);
}
